≫ Добавление документов в таблицу
Если вы ищете информацию о добавлении документов в обычную таблицу, обратитесь к разделу добавления данных из внешних хранилищ.
Добавление документов в реальном времени поддерживается только для таблиц Real-Time и Percolate. Соответствующая SQL-команда, HTTP-эндпоинт или функции клиента вставляют новые строки (документы) в таблицу с предоставленными значениями полей. Не обязательно, чтобы таблица существовала перед добавлением документов в неё. Если таблица не существует, Manticore попытается создать её автоматически. Для получения дополнительной информации см. Автосхема.
Вы можете вставить один или несколько документов со значениями для всех полей таблицы или только для их части. В этом случае остальные поля будут заполнены значениями по умолчанию (0 для скалярных типов, пустая строка для текстовых типов).
Выражения в настоящее время не поддерживаются в INSERT, поэтому значения должны быть указаны явно.
Поле/значение ID можно опустить, так как таблицы RT и PQ поддерживают auto-id. Для таблиц с числовыми ID можно также указать 0 в качестве значения id, чтобы принудительно сгенерировать ID автоматически. Строки с дублирующимися ID не будут перезаписаны через INSERT. Вместо этого для такой задачи используйте REPLACE.
Для таблиц, созданных с id uuid, передавайте явный UUID в виде строки в кавычках или опускайте id, чтобы сгенерировать его автоматически. Явные значения должны соответствовать формату xxxxxxxx-xxxx-Vxxx-Wxxx-xxxxxxxxxxxx, где каждый x — шестнадцатеричная цифра, V — версия (1–8), а W — вариант (8, 9, a или b). Буквы в шестнадцатеричных значениях в верхнем регистре допускаются и приводятся к нижнему регистру. В отличие от числовых ID, 0 не запрашивает автоматическую генерацию UUID.
При использовании HTTP JSON протокола у вас есть два различных формата запроса на выбор: общий формат Manticore и Elasticsearch-подобный формат. Оба формата демонстрируются в примерах ниже.
Кроме того, при использовании формата запроса Manticore JSON помните, что узел doc обязателен, и все значения должны быть предоставлены внутри него.
- SQL
- JSON
- Elasticsearch
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
Общий синтаксис:
INSERT INTO <table name> [(column, ...)]
VALUES (value, ...)
[, (...)]INSERT INTO products(title,price) VALUES ('Crossbody Bag with Tassel', 19.85);
INSERT INTO products(title) VALUES ('Crossbody Bag with Tassel');
INSERT INTO products VALUES (0,'Yellow bag', 4.95);Query OK, 1 rows affected (0.00 sec)
Query OK, 1 rows affected (0.00 sec)
Query OK, 1 rows affected (0.00 sec)При работе с реплицируемыми таблицами нужно использовать специальный синтаксис, чтобы операции записи корректно распространялись на все узлы кластера.
Для всех операций записи (INSERT, REPLACE, DELETE, TRUNCATE, UPDATE) в реплицируемых таблицах необходимо:
- В SQL: Используйте формат
cluster_name:table_nameвместо одного только имени таблицы - В JSON: Указывайте свойство
clusterвместе со свойствомtable
Если не использовать правильный синтаксис, операция завершится ошибкой.
- SQL
- JSON
- PHP
- Python
- Javascript
- Java
- C#
- Rust
INSERT INTO posts:weekly_table(title,price) VALUES ('Crossbody Bag with Tassel', 19.85);
INSERT INTO posts:weekly_table VALUES (0,'Yellow bag', 4.95);Query OK, 1 rows affected (0.00 sec)
Query OK, 1 rows affected (0.00 sec)ПРИМЕЧАНИЕ: Автосхема требует Manticore Buddy. Если это не работает, убедитесь, что Buddy установлен.
Manticore имеет механизм автоматического создания таблиц, который активируется, когда указанная таблица в запросе insert или replace ещё не существует. Этот механизм включен по умолчанию. Чтобы отключить его, установите auto_schema = 0 в разделе Searchd вашего конфигурационного файла Manticore.
По умолчанию все текстовые значения в предложении VALUES считаются имеющими тип text, за исключением значений, представляющих действительные адреса электронной почты, которые обрабатываются как тип string.
Если вы попытаетесь вставить/заменить несколько строк с различными, несовместимыми типами значений для одного и того же поля, автоматическое создание таблицы будет отменено, и будет возвращено сообщение об ошибке. Однако, если различные типы значений совместимы, результирующий тип поля будет таким, который вмещает все значения. Некоторые автоматические преобразования типов данных, которые могут произойти, включают:
- mva -> mva64
- uint -> bigint -> float (это может привести к некоторой потере точности)
- string -> text
Механизм автосхемы не поддерживает создание таблиц с векторными полями (полями типа float_vector), используемыми для поиска сходства KNN (K-ближайших соседей). Чтобы использовать векторные поля в вашей таблице, вы должны явно создать таблицу со схемой, определяющей эти поля. Если вам нужно хранить векторные данные в обычной таблице без возможности поиска KNN, вы можете хранить их как JSON-массив, используя стандартный синтаксис JSON, например: INSERT INTO table_name (vector_field) VALUES ('[1.0, 2.0, 3.0]').
Также следующие форматы дат будут распознаны и преобразованы в метки времени, в то время как все остальные форматы дат будут обрабатываться как строки:
%Y-%m-%dT%H:%M:%E*S%Z%Y-%m-%d'T'%H:%M:%S%Z%Y-%m-%dT%H:%M:%E*S%Y-%m-%dT%H:%M:%s%Y-%m-%dT%H:%M%Y-%m-%dT%H
Имейте в виду, что HTTP-эндпоинт /bulk не поддерживает автоматическое создание таблиц (auto schema). Эту возможность поддерживают только эндпоинт /_bulk (в стиле Elasticsearch) и SQL-интерфейс.
- SQL
- JSON
MySQL [(none)]> drop table if exists t; insert into t(i,f,t,s,j,b,m,mb) values(123,1.2,'text here','test@mail.com','{"a": 123}',1099511627776,(1,2),(1099511627776,1099511627777)); desc t; select * from t;--------------
drop table if exists t
--------------
Query OK, 0 rows affected (0.42 sec)
--------------
insert into t(i,f,t,j,b,m,mb) values(123,1.2,'text here','{"a": 123}',1099511627776,(1,2),(1099511627776,1099511627777))
--------------
Query OK, 1 row affected (0.00 sec)
--------------
desc t
--------------
+-------+--------+----------------+
| Field | Type | Properties |
+-------+--------+----------------+
| id | bigint | |
| t | text | indexed stored |
| s | string | |
| j | json | |
| i | uint | |
| b | bigint | |
| f | float | |
| m | mva | |
| mb | mva64 | |
+-------+--------+----------------+
8 rows in set (0.00 sec)
--------------
select * from t
--------------
+---------------------+------+---------------+----------+------+-----------------------------+-----------+---------------+------------+
| id | i | b | f | m | mb | t | s | j |
+---------------------+------+---------------+----------+------+-----------------------------+-----------+---------------+------------+
| 5045949922868723723 | 123 | 1099511627776 | 1.200000 | 1,2 | 1099511627776,1099511627777 | text here | test@mail.com | {"a": 123} |
+---------------------+------+---------------+----------+------+-----------------------------+-----------+---------------+------------+
1 row in set (0.00 sec)Manticore предоставляет автоматическую генерацию ID для документов, вставляемых или заменяемых в таблицу real-time или Percolate table. Генератор создаёт уникальное числовое значение с гарантиями, перечисленными ниже, но его не следует считать автоинкрементной последовательностью.
Сгенерированное значение ID гарантированно уникально при следующих условиях:
- Значение server_id текущего сервера находится в диапазоне от 0 до 127 и является уникальным среди узлов в кластере, или используется значение по умолчанию, сгенерированное из MAC-адреса в качестве сида
- Системное время не меняется для узла Manticore между перезапусками сервера
- Средняя скорость генерации авто-ID между двумя запусками сервера остается ниже примерно 16 миллионов ID в секунду
Генератор auto ID создаёт 64-битное целое число со следующим распределением:
- Биты с 0 по 23 — это счетчик, который увеличивается при каждом вызове генератора авто ID
- Биты с 24 по 55 хранят время запуска сервера в секундах, закодированное как
(unix_timestamp_at_start - 2019-05-01 00:00:00 UTC) - Биты с 56 по 62 хранят
server_id(значение маскируется в диапазон 0..127)
Такая схема гарантирует, что сгенерированные ID уникальны между узлами кластера и что данные, вставляемые в разные узлы кластера, не создают коллизий. Это особенно важно при работе с реплицируемыми таблицами, поскольку так автогенерируемые ID остаются уникальными на всех узлах репликационного кластера.
Важно: 24-битный счетчик не является жестким ограничением на общее количество документов, которые можно вставить за один запуск сервера. Вы можете вставить более 16 777 216 документов после запуска; ID будут продолжать увеличиваться и оставаться уникальными для этого запущенного процесса. Правило ~16 миллионов ID в секунду важно для уникальности при перезапусках: после перезапуска временная часть должна продвинуться достаточно далеко, чтобы вновь сгенерированные ID не пересекались с ID, созданными до перезапуска.
В результате, первый ID от генератора, используемый для автоматического ID, НЕ равен 1, а является большим числом. Кроме того, поток документов, вставленных в таблицу, может иметь не последовательные значения ID, если между вызовами происходят вставки в другие таблицы, поскольку генератор ID является единым на сервере и используется всеми его таблицами.
Для таблиц с числовыми ID это целочисленный публичный ID документа. Для таблиц с UUID-ID Manticore кодирует его в каноническую строку UUIDv8; клиентам виден только UUID.
- SQL
- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
INSERT INTO products(title,price) VALUES ('Crossbody Bag with Tassel', 19.85);
INSERT INTO products VALUES (0,'Yello bag', 4.95);
select * from products;+---------------------+-----------+---------------------------+
| id | price | title |
+---------------------+-----------+---------------------------+
| 1657860156022587404 | 19.850000 | Crossbody Bag with Tassel |
| 1657860156022587405 | 4.950000 | Yello bag |
+---------------------+-----------+---------------------------+CALL UUID_SHORT(N)Оператор CALL UUID_SHORT(N) позволяет сгенерировать N уникальных 64-битных ID за один вызов без вставки каких-либо документов. Это особенно полезно, когда вам нужно предварительно сгенерировать ID в Manticore для использования в других системах или решениях хранения данных. Например, вы можете сгенерировать автоматические ID в Manticore, а затем использовать их в другой базе данных, приложении или рабочем процессе, обеспечивая согласованные и уникальные идентификаторы в разных средах.
- Example
CALL UUID_SHORT(3)+---------------------+
| uuid_short() |
+---------------------+
| 1227930988733973183 |
| 1227930988733973184 |
| 1227930988733973185 |
+---------------------+Вы можете вставлять в таблицу реального времени не только один документ, но и сколько угодно. Совершенно нормально вставлять пакеты из десятков тысяч документов в таблицу реального времени. Однако важно учитывать следующие моменты:
- Чем больше пакет, тем выше задержка каждой операции вставки
- Чем больше пакет, тем выше скорость индексации, которую вы можете ожидать
- Возможно, вы захотите увеличить значение max_packet_size, чтобы разрешить более крупные пакеты
- Обычно каждая операция массовой вставки считается одной транзакцией с гарантией атомарности, поэтому вы либо получите все новые документы в таблице сразу, либо, в случае сбоя, ни один из них не будет добавлен. Подробнее о пустой строке или переключении на другую таблицу см. в примере "JSON".
Обратите внимание, что HTTP-эндпоинт /bulk не поддерживает автоматическое создание таблиц (auto schema). Эту возможность поддерживают только эндпоинт /_bulk (в стиле Elasticsearch) и SQL-интерфейс. HTTP-эндпоинт /_bulk (в стиле Elasticsearch) позволяет указывать имя таблицы вместе с именем кластера в формате cluster_name:table_name.
Эндпоинт /_bulk принимает идентификаторы документов в том же формате, что и Elasticsearch, и вы также можете включить id в сам документ:
{ "index": { "table": "products", "_id": "1" } }
{ "title": "Crossbody Bag with Tassel", "price": 19.85 }или
{ "index": { "table": "products" } }
{ "title": "Crossbody Bag with Tassel", "price": 19.85, "id": "1" }Для таблицы RT, объявленной с id uuid, /bulk читает UUID из id. /_bulk читает их из метаданных _id или из поля документа id. Оба endpoint'а могут опустить ID, чтобы UUID был сгенерирован автоматически.
Эндпоинт /bulk (режим Manticore) поддерживает поблочное кодирование передачи. Вы можете использовать его для передачи больших пакетов. Это:
- снижает пиковое использование оперативной памяти, уменьшая риск OOM
- уменьшает время отклика
- позволяет обойти ограничение max_packet_size и передавать пакеты гораздо больше максимально разрешенного значения
max_packet_size(128 МБ), например, по 1 ГБ за раз.
- SQL
- JSON
- Elasticsearch
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
Для массовой вставки просто укажите больше документов в скобках после VALUES(). Синтаксис:
INSERT INTO <table name>[(column1, column2, ...)] VALUES(value1[, value2 , ...]), (...)Необязательный список имен столбцов позволяет явно указать значения для некоторых столбцов, присутствующих в таблице. Все остальные столбцы будут заполнены значениями по умолчанию (0 для скалярных типов, пустая строка для строковых типов).
Например:
INSERT INTO products(title,price) VALUES ('Crossbody Bag with Tassel', 19.85), ('microfiber sheet set', 19.99), ('Pet Hair Remover Glove', 7.99);Query OK, 3 rows affected (0.01 sec)Выражения в настоящее время не поддерживаются в INSERT, и значения должны быть указаны явно.
- SQL
- JSON
- Elasticsearch
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
INSERT INTO products(title, sizes) VALUES('shoes', (40,41,42,43));Значение JSON может быть вставлено как экранированная строка (через SQL или JSON) или как объект JSON (через JSON-интерфейс).
- SQL
- JSON
- Elasticsearch
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
INSERT INTO products VALUES (1, 'shoes', '{"size": 41, "color": "red"}');